<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Functions in the pytch module &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Scratch hat blocks → Pytch decorators" href="hat-blocks.html" />
    <link rel="prev" title="Scratch blocks → Pytch functions and methods" href="non-hat-blocks.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="functions-in-the-pytch-module">
<h1>Functions in the pytch module<a class="headerlink" href="#functions-in-the-pytch-module" title="Link to this heading">¶</a></h1>
<p>Various functions, which do not need to refer to a particular Sprite,
are available in the <code class="docutils literal notranslate"><span class="pre">pytch</span></code> module.</p>
<section id="pausing-a-script">
<h2>Pausing a script<a class="headerlink" href="#pausing-a-script" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.wait_seconds">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">wait_seconds</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n_seconds</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pytch.wait_seconds" title="Link to this definition">¶</a></dt>
<dd><p>Make the script calling <code class="docutils literal notranslate"><span class="pre">wait_seconds()</span></code> do nothing for
<code class="docutils literal notranslate"><span class="pre">n_seconds</span></code> seconds before resuming.  This is done by counting
frames, so complicated scripts which render at less than 60fps will
wait for the wrong amount of time; fixing this is on the roadmap.</p>
</dd></dl>

</section>
<section id="creating-a-clone">
<h2>Creating a clone<a class="headerlink" href="#creating-a-clone" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">create_clone_of</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">thing</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>Create a new clone of <code class="docutils literal notranslate"><span class="pre">thing</span></code>.  See <a class="reference internal" href="sprite.html#create-clone-of-for-sprites"><span class="std std-ref">the description in the
Sprites section</span></a> for further details.</p>
</dd></dl>

</section>
<section id="sounds">
<h2>Sounds<a class="headerlink" href="#sounds" title="Link to this heading">¶</a></h2>
<p>Most sound functionality is accessed through <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> methods.  See
<a class="reference internal" href="sprite.html#methods-playing-sounds"><span class="std std-ref">the relevant part of the Sprites
section</span></a> for details.  However, the function
to stop all sounds from playing is in the <code class="docutils literal notranslate"><span class="pre">pytch</span></code> module:</p>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.stop_all_sounds">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">stop_all_sounds</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pytch.stop_all_sounds" title="Link to this definition">¶</a></dt>
<dd><p>Stop all sounds from playing.</p>
</dd></dl>

</section>
<section id="asking-the-user-a-question">
<h2>Asking the user a question<a class="headerlink" href="#asking-the-user-a-question" title="Link to this heading">¶</a></h2>
<p>This is usually done with <a class="reference internal" href="sprite.html#sprite-method-ask-and-wait"><span class="std std-ref">a Sprite
method</span></a>, but the following function is
also available if required.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.ask_and_wait">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">ask_and_wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prompt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pytch.ask_and_wait" title="Link to this definition">¶</a></dt>
<dd><p>Ask the user a question, using a pop-up input box.  The given
<code class="docutils literal notranslate"><span class="pre">prompt</span></code> (if not <code class="docutils literal notranslate"><span class="pre">None</span></code>) is shown as part of the input box.
The script calling <code class="docutils literal notranslate"><span class="pre">pytch.ask_and_wait()</span></code> pauses until the user
answers the question.</p>
<p>The user’s answer is returned to the calling script.</p>
<p>If a question is already being asked, the new question is put in a
queue, to be asked once all existing questions have been answered
by the user.</p>
</dd></dl>

</section>
<section id="sensing-whether-a-particular-key-is-pressed">
<h2>Sensing whether a particular key is pressed<a class="headerlink" href="#sensing-whether-a-particular-key-is-pressed" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.key_pressed">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">key_pressed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key_name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pytch.key_pressed" title="Link to this definition">¶</a></dt>
<dd><p>Give a <code class="docutils literal notranslate"><span class="pre">True</span></code>/<code class="docutils literal notranslate"><span class="pre">False</span></code> answer as to whether the key with name
<code class="docutils literal notranslate"><span class="pre">key_name</span></code> is currently pressed.</p>
</dd></dl>

</section>
<section id="broadcasting-messages">
<h2>Broadcasting messages<a class="headerlink" href="#broadcasting-messages" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.broadcast">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">broadcast</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message_string</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pytch.broadcast" title="Link to this definition">¶</a></dt>
<dd><p>Broadcast the message <code class="docutils literal notranslate"><span class="pre">message_string</span></code>, launching any scripts
with a matching <code class="docutils literal notranslate"><span class="pre">&#64;pytch.when_I_receive()</span></code> decorator (hat-block).
The script calling <code class="docutils literal notranslate"><span class="pre">broadcast()</span></code> continues, with the responses
happening concurrently.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pytch.broadcast_and_wait">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">broadcast_and_wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message_string</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pytch.broadcast_and_wait" title="Link to this definition">¶</a></dt>
<dd><p>Broadcast the message <code class="docutils literal notranslate"><span class="pre">message_string</span></code>, launching any scripts
with a matching <code class="docutils literal notranslate"><span class="pre">&#64;pytch.when_I_receive()</span></code> decorator (hat-block).
The script calling <code class="docutils literal notranslate"><span class="pre">broadcast_and_wait()</span></code> waits until all those
scripts have finished before continuing.</p>
</dd></dl>

</section>
<section id="stopping-all-scripts">
<h2>Stopping all scripts<a class="headerlink" href="#stopping-all-scripts" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.stop_all">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">stop_all</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pytch.stop_all" title="Link to this definition">¶</a></dt>
<dd><p>Stop all currently-executing scripts.  Also stop all sounds,
delete all clones, abandon all “ask and wait” questions, and
clear all speech bubbles.</p>
<p><code class="docutils literal notranslate"><span class="pre">pytch.stop_all()</span></code> does the same job as the “red stop” button.</p>
</dd></dl>

</section>
<section id="variable-watchers">
<h2>Variable watchers<a class="headerlink" href="#variable-watchers" title="Link to this heading">¶</a></h2>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is an experimental part of Pytch.  In future versions of
Pytch, we might change the way variable watchers work, depending on
user feedback.</p>
</div>
<p>In Scratch, you can “show” a variable, either by ticking a box in the
UI, or by using the <em>show variable MY-VARIABLE</em> block.  Pytch does not
have a box to tick, but does have the <code class="docutils literal notranslate"><span class="pre">pytch.show_variable()</span></code>
function.  The simplest way to show a variable is to use
<code class="docutils literal notranslate"><span class="pre">pytch.show_variable()</span></code> like this:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@pytch</span><span class="o">.</span><span class="n">when_I_receive</span><span class="p">(</span><span class="s2">&quot;set-up-score&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">set_up_score</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">score</span> <span class="o">=</span> <span class="mi">0</span>
<span class="hll">    <span class="n">pytch</span><span class="o">.</span><span class="n">show_variable</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="s2">&quot;score&quot;</span><span class="p">)</span>
</span></pre></div>
</div>
<p>As this example shows, you give Pytch two pieces of information: you
tell it who owns the variable you want to show (here, the <code class="docutils literal notranslate"><span class="pre">self</span></code>
sprite), and you tell it the <strong>name</strong> of the variable, as a string
(here, <code class="docutils literal notranslate"><span class="pre">&quot;score&quot;</span></code>).  In this simple form, the Stage will show a small
‘watcher’ box with a <em>label</em> and the variable’s <em>value</em>.  By default,
the label is the same as the variable name, and the watcher appears in
the top-left corner of the stage.</p>
<p>You can tell Pytch where to show the watcher by giving it more
information.  You can choose whether to fix the <em>left</em> or <em>right</em> edge
of the box, by giving the stage <em>x</em>-coordinate where you want that
edge to be.  You can separately choose whether to fix the <em>top</em> or
<em>bottom</em> edge, by giving a stage <em>y</em>-coordinate.  You can tell also
Pytch what label to use, instead of the variable name.</p>
<p>To pass any of these arguments, use Python’s <em>named argument</em> syntax.
In this example, we pass <code class="docutils literal notranslate"><span class="pre">label</span></code>, <code class="docutils literal notranslate"><span class="pre">top</span></code>, and <code class="docutils literal notranslate"><span class="pre">right</span></code> as named
arguments:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">pytch</span><span class="o">.</span><span class="n">show_variable</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="s2">&quot;score&quot;</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s2">&quot;SCORE:&quot;</span><span class="p">,</span> <span class="n">top</span><span class="o">=</span><span class="mi">176</span><span class="p">,</span> <span class="n">right</span><span class="o">=</span><span class="mi">236</span><span class="p">)</span>
</pre></div>
</div>
<p>This will set up a watcher for <code class="docutils literal notranslate"><span class="pre">self.score</span></code>, showing the value with
the label <code class="docutils literal notranslate"><span class="pre">SCORE:</span></code>, a little way in from the top-right corner of the
stage.</p>
<section id="sprite-variables-and-clones">
<h3>Sprite variables and clones<a class="headerlink" href="#sprite-variables-and-clones" title="Link to this heading">¶</a></h3>
<p>In Scratch, you can only show the original instance’s value of a “for
this Sprite only” variable.  In Pytch, you can show a clone’s value of
the variable.  When a clone is running a method, <code class="docutils literal notranslate"><span class="pre">self</span></code> refers to
that clone.</p>
<p>When a clone is deleted, any variable watchers showing variables
belonging to that clone are removed.</p>
</section>
<section id="project-level-variables">
<h3>Project-level variables<a class="headerlink" href="#project-level-variables" title="Link to this heading">¶</a></h3>
<p>Sometimes you will have a variable at the top level of your project, outside any
Sprite or Stage.  These are also called “global” variables.  As a
special case, to show these variables, you can use <code class="docutils literal notranslate"><span class="pre">None</span></code> as the
first argument to <code class="docutils literal notranslate"><span class="pre">show_variable()</span></code>, for example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">score</span> <span class="o">=</span> <span class="mi">100</span>

<span class="k">class</span><span class="w"> </span><span class="nc">Ship</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Sprite</span><span class="p">):</span>
    <span class="c1"># [...]</span>
    <span class="nd">@pytch</span><span class="o">.</span><span class="n">when_this_sprite_clicked</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">show_score</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="hll">        <span class="n">pytch</span><span class="o">.</span><span class="n">show_variable</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="s2">&quot;score&quot;</span><span class="p">)</span>
</span></pre></div>
</div>
</section>
<section id="advanced-usage">
<h3>Advanced usage<a class="headerlink" href="#advanced-usage" title="Link to this heading">¶</a></h3>
<p>Most Pytch programs will not need to use the techniques in this
section.</p>
<p>In fact any attribute will do, so you can for example give the name of
a <em>property</em> to compute the value dynamically.  This property will be
accessed 60 times a second so should not do any heavy computation.</p>
<p>So far we have given examples where the “variable owner”, i.e., the
first argument to <code class="docutils literal notranslate"><span class="pre">pytch.show_variable()</span></code>, is a Sprite, or your
Stage, or <code class="docutils literal notranslate"><span class="pre">None</span></code> to mean a global variable.  It can also be any
other object in your program, for instance a non-Actor class:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="k">class</span><span class="w"> </span><span class="nc">GameState</span><span class="p">:</span>
</span><span class="hll">    <span class="n">score</span> <span class="o">=</span> <span class="mi">100</span>
</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Ship</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Sprite</span><span class="p">):</span>
    <span class="c1"># [...]</span>
    <span class="nd">@pytch</span><span class="o">.</span><span class="n">when_this_sprite_clicked</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">show_score</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="hll">        <span class="n">pytch</span><span class="o">.</span><span class="n">show_variable</span><span class="p">(</span><span class="n">GameState</span><span class="p">,</span> <span class="s2">&quot;score&quot;</span><span class="p">)</span>
</span></pre></div>
</div>
</section>
</section>
<section id="suspiciously-long-running-loops-outside-event-handlers">
<h2>Suspiciously long-running loops outside event handlers<a class="headerlink" href="#suspiciously-long-running-loops-outside-event-handlers" title="Link to this heading">¶</a></h2>
<p>Most users will not need to use the functionality described in this
section.</p>
<p>In Pytch, it is common to have an infinite loop (e.g., <code class="docutils literal notranslate"><span class="pre">while</span> <span class="pre">True</span></code>)
inside an event handler.  Such a loop runs at one iteration per
display frame.</p>
<p>But an infinite loop at the top level of your program will prevent
your project even starting.  For example,</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">pytch</span>

<span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
    <span class="k">pass</span>
</pre></div>
</div>
<p>Pytch detects this situation, and raises an error.  It is impossible
for Pytch to tell when a loop is truly infinite, though, and so it
raises this error if more than 1000 iterations of loops happen when
launching your program.  Rarely, you might genuinely have a program
which needs a longer-running loop at top-level.  If so, you can raise
the limit as follows.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.set_max_import_loop_iterations">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">set_max_import_loop_iterations</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n_iters</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pytch.set_max_import_loop_iterations" title="Link to this definition">¶</a></dt>
<dd><p>Set the maximum number of loop iterations permitted at top level
before an error is raised.</p>
</dd></dl>

<p>For example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">pytch</span>

<span class="c1"># Without the following line, the loop below would raise an error.</span>
<span class="n">pytch</span><span class="o">.</span><span class="n">set_max_import_loop_iterations</span><span class="p">(</span><span class="mi">2000</span><span class="p">)</span>

<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1200</span><span class="p">):</span>
    <span class="k">pass</span>
</pre></div>
</div>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Writing Pytch programs</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="sprite.html">Sprites</a></li>
<li class="toctree-l2"><a class="reference internal" href="stage.html">The stage</a></li>
<li class="toctree-l2"><a class="reference internal" href="non-hat-blocks.html">Scratch blocks → Pytch functions and methods</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Functions in the pytch module</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#pausing-a-script">Pausing a script</a></li>
<li class="toctree-l3"><a class="reference internal" href="#creating-a-clone">Creating a clone</a></li>
<li class="toctree-l3"><a class="reference internal" href="#sounds">Sounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="#asking-the-user-a-question">Asking the user a question</a></li>
<li class="toctree-l3"><a class="reference internal" href="#sensing-whether-a-particular-key-is-pressed">Sensing whether a particular key is pressed</a></li>
<li class="toctree-l3"><a class="reference internal" href="#broadcasting-messages">Broadcasting messages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#stopping-all-scripts">Stopping all scripts</a></li>
<li class="toctree-l3"><a class="reference internal" href="#variable-watchers">Variable watchers</a></li>
<li class="toctree-l3"><a class="reference internal" href="#suspiciously-long-running-loops-outside-event-handlers">Suspiciously long-running loops outside event handlers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="hat-blocks.html">Scratch hat blocks → Pytch decorators</a></li>
<li class="toctree-l2"><a class="reference internal" href="costume-specs.html">Defining costumes</a></li>
<li class="toctree-l2"><a class="reference internal" href="backdrop-specs.html">Defining backdrops</a></li>
<li class="toctree-l2"><a class="reference internal" href="sound-specs.html">Defining sounds</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-threading.html">Running many scripts at once</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../developer.html">Developer documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>